fix: process page HTML outside PHP's output-buffer display handler - #1132

Production sites crashed with Optml_Manager::replace_content(): Cannot use output buffering in output buffering display handlers (issue #1126). The full-page replacement now runs outside PHP's display-handler context, where nested output buffering is legal and fatal errors keep their real message.

What changed

• Capture buffer — process_template_redirect_content() starts a capture buffer whose handler is a named method (handle_buffer_fallback). When a third party flushes the buffer early, the handler passes the content through unprocessed and logs it: running the filter graph inside a PHP display handler would turn any third-party ob_*() call into an uncatchable engine fatal — the crash this rework removes. Only the legacy mode keeps in-handler processing.

• close_buffer() — flushes third-party buffers stacked above ours, captures our own buffer, processes the HTML in normal execution context, and echoes the result.

• Buffer ownership — before: ob_end_flush() popped whichever buffer was on top. After: we only consume the buffer we started, verified by nesting level and handler identity (ob_get_status()['name'] must report Optml_Manager::handle_buffer_fallback), so a foreign buffer at our recorded level is never captured or closed.

• close_final_buffer() — a re-armed buffer captures output echoed by later shutdown callbacks and processes it at shutdown priority PHP_INT_MAX.

• do_url_replacement() — replaces extracted URLs in one pass per size-bounded chunk instead of one full-page preg_replace() per URL. Benchmark on a 1.2 MB page: 300 URLs in 4 ms instead of 77 ms, 900 URLs in 13 ms instead of 216 ms. Peak memory stays the same; the win is CPU time and allocation churn. Chunks flush at 200 URLs or 24KB of quoted pattern, so the compiled regex stays within PCRE's ~64KB limit even for kilobyte-long signed CDN URLs.

• Escape hatch — return false from the new optml_capture_at_shutdown filter to restore the legacy in-handler flow.

Shutdown flow

flowchart LR
    A[Changed:<br/>page renders into<br/>plain capture buffer]:::changed --> B[shutdown:<br/>close_buffer]
    B --> C[New:<br/>flush third-party<br/>buffers above]:::added
    C --> D{New:<br/>our buffer<br/>intact?}:::added
    D -- Yes --> E[Changed:<br/>process HTML<br/>outside handler]:::changed
    E --> F[Echo optimized page]
    F --> G[New:<br/>re-arm for late<br/>shutdown output]:::added
    D -- No --> H[Stand down:<br/>early-flushed content<br/>passed through, logged]

    classDef added fill:#1a7f37,color:#fff,stroke:#116329,stroke-width:3px
    classDef changed fill:#9a6700,color:#fff,stroke:#5c3d00,stroke-width:3px,stroke-dasharray:6 3

QA

1. Connect the site in WP Admin → Media → Optimole. Create wp-content/mu-plugins/ob-probe.php with:

   <?php
   add_filter( 'optml_url_pre_process', function ( $html ) {
       ob_start();
       echo 'probe';
       ob_get_clean();
       return $html;
   } );

   Open any frontend page.

   Expect: the page renders, image URLs point to i.optimole.com, and wp-content/debug.log contains no Cannot use output buffering fatal. Without this fix, the page terminates with that fatal.

2. Remove the mu-plugin. Add add_filter( 'optml_capture_at_shutdown', '__return_false' ); to the theme's functions.php. Open a frontend page and view the source.

   Expect: image URLs still point to i.optimole.com (legacy in-handler flow).

3. Remove the filter. Install and activate TranslatePress. Translate a page that contains images and open the translated page.

   Expect: the translated text and i.optimole.com image URLs appear together.

🤖 Generated with Claude Code